REST Reference Builder
Description
The REST Reference Builder is used to define endpoints, authentication requirements, and more for querying a third-party REST API.
Discussion
The REST Reference Builder creates an Xbasic class that can be used to make API calls against a third-party REST service in a server-side script. Scripts to query the API are inserted into server-side code using the REST Reference Genie. The genie generates the code required to call the endpoint configured in the REST Reference. Endpoints, or Actions, are made available as methods of the Xbasic class for the REST Reference.
Creating a REST Reference
To create a REST Reference, select the "Web Services" option on the Web Projects Control Panel. Then click the New button. This opens the New Service Type dialog.
In the REST section, click Create a new definition to consume a REST service to create a new REST Reference.
The REST Reference can be created from an existing Google Service, imported from a Swagger definition, or built from scratch.
To create a REST Reference for a Google service, click the Import Google Service... URL and select the desired Google service. Refer to Google's documentation for the desired API for more information about using the selected API.
Some REST APIs provide a Swagger definition. A Swagger definition is a JSON document that describes a RESTful API. If the API that you'd like to use provides a Swagger definition, you can use the the Import Swagger... link to import the Swagger definition. The Swagger definition can be pasted directly into the window, imported from a URL, or loaded from a local file. Alpha Anywhere will use the definition to generate the REST Reference.
After entering a Name, you can click Create to generate the REST Reference. Alpha Anywhere will create a new file with an "a5restapi" extension with the name specified in the Create REST Reference dialog. The Edit REST Service Definition may also automatically open.
Overview of the Edit REST Service Definition dialog
The Edit REST Service Definition dialog contains the REST Reference definition. Included in the definition is the REST API URL, endpoints (Actions), Named Resource Providers, and other information required to call the API.
If you don't import a Google service, the Edit REST Service Definition dialog opens after creating the service.
Properties
The Properties tab contains the base URL and Provider information for the API:
- Property
- Description
- Resource URL
The base path for the REST service. E.g. https://www.myservice.com/v1/api/
- Public Access - Provider
The API endpoint for endpoints that don't require authentication. Public endpoints may require an API key but generally don't require the user to provide credentials, such as OAuth credentials.
- Private Access - Provider
The API endpoint for endpoints that require authentication, such as OAuth.
Endpoints for the REST API are added as Actions. An Action specifies the Path, parameters, the method (GET, POST, etc), and the schema for content sent in the body and header of the request.
You can add an Action using the Add Action button. You can also create an Action by importing from a CURL command via Import from CURL....
Placeholders can be used where needed in the URL and body using the syntax {placeholder_name}. "placeholder_name" corresponds to the value of Name for a Parameter, defined at the bottom of the dialog using the Add Parameter button. Any headers required by the endpoint are also defined as Parameters.
REST Reference Genie
The REST Reference Genie generates the Xbasic to call an endpoint defined in a REST Reference. The genie is found in the context menu for the Xbasic editor. Right-click anywhere in the Xbasic editor, then select Genies... > REST Reference call....
Select the REST service in the Service column that you'd like to use, then choose the endpoint to call in the Method column. Alpha Anywhere will display the Xbasic to call the endpoint in the code window at the bottom of the dialog. Click Copy Example to Clipboard to copy the code. When you click OK, the code for the selected method is automatically inserted into the Xbasic editor at the cursor location.
The Generate dropdown box at the top fo the dialog can be used to add help information to the Xbasic in the form of comments.
Example: Building a REST Reference using the Random Useless Facts API
In this example, we'll build a REST Reference for the Random Useless Facts API. The Random Useless Facts API is a free public REST API that returns a random useless fact. The API has two end points: /random, which returns a random useless fact, and /today which returns the useless fact of the day. Facts can be retrieved in German (de) or English (en) in a variety of formats (.html, .json, .txt, or .md). For example, the URL to retrieve a random fact in English as JSON is:
https://uselessfacts.jsph.pl/random.json?language=en
Creating the REST Reference
To create a new REST Reference, select the "Web Services" option on the Web Projects Control Panel. Then click the New button.
When the New Service Type dialog appears, select Create a new definition to consume a REST service in the REST portion of the dialog.
Enter a name for the REST Reference then click Create. In this example, we'll name the REST Reference randomFact.
After creating the REST Reference, Alpha Anywhere opens the reference for editing. The Edit REST Service Definition builder is where you specify the REST API URL, authentication requirements, and endpoints (Actions) that you'd like to call.
Next, we'll configure the Resource URL for the API. Add the following information to the Edit REST Service Definition builder:
- Resource URL
https://uselessfacts.jsph.pl
The Random Useless Fact API does not require authentication, so the Public Access and Private Access properties should be blank.
Now that we've defined the Resource URL, we can add Actions for the /random and /today endpoints. Click the Add Action button to add a new action.
The first action we'll add will call the /today endpoint. Enter the following values in for the corresponding property in the Action editor:
- Property
- Value
- Name
today
- Method
get
- Access
public
Next, we'll define the Path. Click the smart field button for the Path property. Then, enter the following values in the Path and Query Parameters text boxes:
- Property
- Value
- Path
/today{format}
- Query Parameters
language={language}
The /today endpoint has two optional parameters you can use to request a specific file format and language to use when returning the fact. The file format is part of the path. For example, /today.json will return the fact in JSON format.
To make the call dynamic, we can specify a placeholder in the path representing the optional format: {format}.
The language is passed to the endpoint as a query parameter. E.g. /today?language=en returns the fact in English. We can use a placeholder, {language}, in the Query Parameters to make the is a placeholder for the requested language.
Click OK to save the Path definition.
After defining the Path, we next need to define the parameters used in the path definition. We'll configure the {language} placeholder first. Alpha Anywhere should automatically add a parameter for language after saving the Path.
If there are no parameters listed in the dialog, you can create the language parameter using Add Parameter: click the Add Parameter button to add a parameter, select the Query option, then click OK.
Verify that the Query parameter for language has the following values for Name and Location:
- Property
- Value
- Name
language
- Location
Query
Next, we'll create the format parameter. Click Add Parameter, select the Path option, then click OK.
Select the new path parameter. Then, enter the following values for the Name and Location properties:
- Property
- Value
- Name
format
- Location
Path
When you've finished defining the {format} parameter, you can test the Action. Click Test to open the Action tester
Enter a language and format in the language and format. The Random Useless Fact API supports the following values for language and format:
- Language Options
- Description
- en
Return the fact in English
- de
Return the fact in German
- Format Options
- Description
- .html
Return the fact formatted as HTML.
- .json
Return the fact formatted as JSON.
- .txt
Return the fact formatted as plain text.
- .md
Return the fact formatted as Markdown
The image below shows the result of calling the endpoint with language set to "en" and format set to ".json":
When you are done testing the endpoint, click Save to save the Action.
Repeat the process above to add the /random endpoint. The /random endpoint takes the same optional parameters as /today. The Action definition should be identical to /today with the exception of the path portion for the Path parameter, which is defined as /random{format}.
After adding the /random Action, save the REST Service Definition. It can now be added to any Xbasic script using the REST Reference Genie.
See Also